Is there a cleaner way of handling default config values? I couldn't find where exactly.

Since you've already added a default value in Joi validation, there's no need to duplicate it here (Joi validation actually mutates the object)
Would it make sense to add a minDepth option as well? Would the user sometimes not want to have h2 headings?

Since you've already added a default value in Joi validation, there's no need to duplicate it here (Joi validation actually mutates the object)

Weird because I get the following error when I don't have the null coalescing part:

TypeError: Cannot destructure property 'maxDepth' of 'tableOfContents' as it is undefined.

git diff of the code change:

diff --git a/packages/docusaurus-theme-classic/src/theme/TOC/index.tsx b/packages/docusaurus-theme-classic/src/theme/TOC/index.tsx
index 83c3d2930..4dfe9038c 100644
--- a/packages/docusaurus-theme-classic/src/theme/TOC/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/TOC/index.tsx
@@ -28,7 +28,7 @@ export function TOCHeadings({
   depth: headingLevel,
 }: TOCHeadingsProps): JSX.Element | null {
   const {tableOfContents} = useThemeConfig();
-  const maxDepth = tableOfContents?.maxDepth ?? 3;
+  const { maxDepth } = tableOfContents;
   if (!toc.length) {
     return null;
   }

Would it make sense to add a minDepth option as well? Would the user sometimes not want to have h2 headings?

Personally I think this feels like an anti-pattern since you generally want to utilize all markdown heading levels. I could see it for some niche cases like having a single h2 on a page and not wanting to nest all of your h3 inside, but feels funny to have it on site-wide in the theme config.

Happy to implement it if others feel differently.

Weird because I get the following error when I don't have the null coalescing part

Oh yeah, you need to provide a default value for the entire tableOfContents config object as well

but feels funny to have it on site-wide in the theme config.

I'm thinking about adding a per-doc option minLevel as well, and just for the sake of uniformity, I think a site-level config is worth it. But seems @slorber doesn't particularly like too many APIs, so let's see🤷‍♂️

Since you've already added a default value in Joi validation, there's no need to duplicate it here (Joi validation actually mutates the object)

Addressed this in 0785423

For consistency I'd rather have min/max everywhere, even if min is less likely to be used and mostly for weird use-cases

I see a better solution here: record "the nearest h2~h6 node indices" as an array closestNode[] where closestNode[level] is the index of the closest node with level h<level> and closestNode[0] = closestNode[1] = -1.

On each node you find the value in closestNode with a smaller level than curr.level and the largest index possible, and then update closestNode:

const closestNode = Array(7).fill(-1);
headings.forEach((curr, currIndex) => {
  curr.parentIndex = Math.max(...closestNode.slice(0, curr.level));
  closestNode[curr.level] = currIndex;
});

Of course this would mean a little inline comments, but the code is much shorter and also more straightforward IMO

Math.max(...prevIndexForLevel.slice(2, 2)) = Math.max(...[]) = -Infinity, although that doesn't break the algorithm, does it really make sense?

Makes as much sense to me as having indexes for "levels" 0 and 1, I figure. It's nice to be explicit about only starting at index 2 🤔

🤪 my head hurts 🤯 will have to take more time reviewing this.

We need more test cases to cover the edge cases

I tested a few edge cases locally (never committed the changes) and it seemed to work somewhat well.

My personal take (as a drive-by contributor, feel free to ignore) is that while the TOC should never break, documents that have wonky heading formatting won't suffer too much from having a wonky TOC.

Agree, just added tests to ensure the behavior with wonky TOC stays the same over time :)

As we discussed it earlier, can we remove this redundant anchor__X class for each of headings levels? Maybe use more specific name like docusaurus_anchor instead of just anchor?

I'm not sure to understand what you mean here.

We want to get only the anchors from min to max, so we need levels in classnames otherwise we'd select more anchors and it could mess-up with the TOC algorithm (an anchor that is not in the TOC should never be considered as "active" because we wouldn't be able to highlight it because it doesn't appear in the TOC)

could mess-up with the TOC algorithm

How can something break if we get all anchor links? If it important, we can actually filter out anchor links based on its heading tag instead class.

It is important. Consider this scenario:

• We config to only use h2 in toc (not h3)
• We scroll to a h3 heading

Then, the h3 heading is considered the "active" one but it's not in the TOC, so nothing is highlighted (while we should highlight the parent h2)

we can actually filter out anchor links based on its heading tag instead class.

You can do select("h2 h3 h4") or select("*").filter(is("h2 h3 h4")), both would lead to the same result

It's a best practice to create a more precise selector / query in the first place when possible

both would lead to the same result

Yes, but we can get rid of extra classes, why do we need them if can avoid using them?

It doesn't seem like a big deal to me to keep them and would be a CSS breaking change to remove them now

Also nothing guarantees that a user won't use headings in other places of its theme for weird reasons, and we may want to avoid that it conflicts with the TOC algorithm by not using "h2 h3" selector on purpose. Classnames help remove the opportunities for such a conflict

We've already marked this PR as BC, so it's good time to get rid of this extra thing.

Right, but our header-anchors will still have generic class anchor, though could make it even more specific. I suggest removing only heading-specific classes, and use heading tag level instead in TOC algorithm.

Oh I thought you wanted to remove both classes

If you want to refactor to h2.anchor, h3.anchor, I'm fine with the idea (and .anchor__h2 is quite new so it's a smaller breaking change)